Skip to main content
Version: 5.3.0.0

Serializers

Concept​

All channels writing a byte stream need a serializer to create the content from a message.

:::info Inbound vs. Outbound Note that the terms Inbound channel and Outbound channel do not refer to the direction in which the data flows, but to the initiator of the call.

  • An inbound channel might write data (e.g., the HTTP GET Receiver) and therefore needs a serializer.
  • Example: If you want to write a CSV file using the File Writer, you need a serializer to transform the DOM tree of the structured message into the byte stream written to the file. :::

Some serializers need information from special Message types (e.g., the Type based serializer). When configuring these serializers, the user must select an appropriate message type.

Other serializers need no message type to work (e.g., the XML writer), while some may use a message type but can also function without one (e.g., the CSV writer).

Creation​

A serializer is always created when configuring a Stream channel.

  1. Select a serializer.
  2. Select an appropriate message type (if necessary).
  3. Click on the button marked with ... to configure the serializer (if necessary).

:::tip Auto-selection If no serializer is selected yet (or only the binary writer is selected) and you select a message type associated with a particular serializer, that serializer is automatically selected. :::

Output Filters​

Below the serializer selection line, you can select a Stream filter by double-clicking the arrow -->. This allows you to build a sequence of filters. To configure a filter, double-click on its name in the sequence.

CSV Writer​

Description​

The CSV writer is a serializer that transforms a structured Message representing a list of records into a CSV text stream.

Creation​

A CSV writer is created by selecting it in the appropriate Stream channel.

  • With Message Type: You may select a Message type describing the structure of the CSV. The element names of the output message are compared with the names of the declared fields within the message type. If fields are missing in the output message, the serializer adds empty fields.
  • Without Message Type: The output message must always contain the expected number of fields to write to the CSV. If a field value is not available, the message must contain an empty element for that field.

Configuration​

Apart from selecting a message type, the following options are available:

  • Encoding: Select the character set and encoding of the text stream.
  • Separator character: The character used to separate fields in the stream. Note that a tabulator is written as \t.
  • Quote character: The character used to surround (quote) the values.
  • Escape character: The character used to enable inclusion of the quote character by escaping its special meaning. Normally this is the quote character again (e.g., if the quote character is contained in the text, it is represented as two quote characters).
  • Line end: Defines the character used to terminate a record.
  • headline: Enter a string which is written unchanged as the first line of the output stream.

Type Based Serializer​

Description​

A type based serializer writes data in a format according to the information in a Message type with default type INTERNAL.

Creation​

A type based serializer is created by selecting it in the Stream channel.

:::warning Requirement Because the processing depends on a message type, you MUST select an appropriate Message type describing the structure. In the dropdown box, you can only select message types with format type INTERNAL. :::

Configuration​

The core configuration is contained within the message type itself.

Format Editor​

For an INTERNAL message format, you can define a set of delimiters via the Format properties (enabled only if the default format is INTERNAL).

You can change delimiters defined for the selected element itself and its sub-elements (descendants).

Delimiter Properties:

PropertyDescription
LevelAssigns consecutive sets of delimiter parameters to delimited nodes in the Encoder node hierarchy.
DelimiterAny alphanumeric sign(s), including control characters (e.g., \r, \n).
Optional modeSpecifies how delimiters for optional nodes are handled when nodes are absent or empty. (See details below).
Terminator modeSpecifies how delimiters are handled for a specific terminator node.
Repeat symbolA delimiter used to delimit repetitive occurrences (e.g., * in a^b^c1*c2*c3*c4^).

Optional Mode Options:

  • Never: If node is absent, delimiter is not allowed in input or output.
  • Allow: If node is absent, delimiter is allowed in input but not emitted in output.
  • Cheer: If node is absent, delimiter is allowed in input and emitted in output.
  • Force: If node is absent, delimiter must appear in input and will be emitted in output.

Escaping: To include a delimiter inside a string literal, you must escape it using the backslash (\). To escape a backslash itself, use it twice (\\).

Serializer Options​

Apart from the message type, you can configure:

  • Encoding: The encoding of the text stream.
  • Truncate too long values: If checked, Orchestra truncates values that exceed the defined length.

XML Writer​

Description​

The XML writer transforms a structured Message (internally represented as a DOM tree) into an XML data stream. Every structured message in Orchestra can be written as XML.

Configuration​

  • Encoding: Select character set and encoding.
  • Content type: Change the content type (e.g., text/xml, text/html, application/xml, application/xhtml+xml).
  • Document type declaration: Declare a DTD for the XML header (e.g., html to write <!DOCTYPE html>).
  • Processing Instruction: Declare a PI for the XML header (typically stylesheet declarations).
  • Insert newlines: Format output with line breaks.
  • Encode non ASCII as entity ref: Encodes characters outside the ASCII range.

Excel Writer​

Description​

The Excel writer reads CSV files and writes the tables into a Microsoft Excel file.

Configuration​

  • Sheet name: Input the sheet name.
    • Excel version: Choose "xls" (before 2007) or "xlsx" (after 2007).
  • Headline: Check if the Excel sheet has a header line.

Binary Writer​

Description​

The binary writer acquires the binary content of a message and writes it unchanged to the output stream. It is typically used for messages created by the Binary Reader (e.g., PDF content). If used on a structured message, the DOM tree is written as plain XML.

Configuration​

A binary writer requires no configuration.

EDI Message Writer​

Description​

Transforms a structured Message representing a list of records into an EDIFACT text stream.

Configuration​

  • EDI-Variant: Choose the EDI variant.
  • Mode:
    • Dynamic: Creates message structure dynamically.
    • Type: Uses internal message type for serialization.
  • Type lookup: Choose the font/type to be used.
  • Encoding: (Only in Type mode) Specify EDI fields here.
  • Separators: Specify separators (commonly . and ,).

Text Writer​

Description​

A serializer that writes the content of a structured message as text.

Configuration​

  • Encoding: Choose the encoding/font.
  • Newline after element: List elements that should have a newline appended after them. Writing * adds a newline after every element.

Fixed Column Writer​

Description​

Transforms a structured Message representing a list of records into a file with fixed lengths and fields. Every field consists of a key-value pair defining the column name and value.

Configuration​

  • Encoding: Choose stream encoding.
  • Line end: Windows (\r\n), Unix (\n), or macOS (\r).
  • Columns: Define the columns.
    • Insert Key: Add a new line.
    • Backspace Key: Add rows at any position.
    • Delete Key: Remove rows.

Fixed Length Field Writer​

Description​

Transforms a structured Message representing a list of records into a fixed-length text stream.

Configuration​

  • Encoding: Choose stream encoding.
  • Line end: Windows (\r\n), Unix (\n), or macOS (\r).

JSON Writer​

Description​

Transforms a structured Message (DOM tree) into a JSON data stream.

Configuration Options​

  • Readable output: Inserts newlines and tabs to make the JSON human-readable.

The JSON serializer can operate in five different modes:

1. Generic Mode​

No schema and no message type are configured. All information needed to write the JSON stream must be contained in the message.

  • Invalid XML tag names: If an XML element has an attribute original_name, its value is written as the JSON property name (used for names invalid in XML).
  • Simple Data Values: Written as JSON strings (e.g., "10.2") unless the Consider xsi:type checkbox is set. If set, XML attributes like xsi:type="xs:integer" are used to determine if the value should be a number, boolean, etc.
  • Null values: If xsi:nil="true" is present (and Consider xsi:type is checked), a JSON null is written. Otherwise, an empty string "" is written.

Arrays in Generic Mode: To prevent repeated elements from creating duplicate keys (which is invalid JSON), repeated elements must be marked. Alternatively, if the root contains a sequence of records, check Message contains array to treat the root as an array.

Example XML:

<root>
    <row>
        <ident>001023</ident>
        <name>SevenUp</name>
    </row>
    <row>
        <ident>001025</ident>
        <name>Bluna</name>
    </row>
</root>

Resulting JSON (with "Message contains array" checked):

[
    { 
      "ident": "001023", 
      "name": "SevenUp"
    },
    { 
      "ident": "001025", 
      "name": "Bluna"
    }
]

2. Native Mode​

Expects a native JSON message. An error occurs if a structured DOM (XML) message is provided.

3. Typed Mode (XML Schema)​

The user selects an XML schema. The serializer uses schema information to:

  • Write arrays if element cardinality is > 1.
  • Write JSON values according to the simple element types defined in the schema.

4. Typed Mode (Message Type)​

Uses a selected Message Type to serialize to JSON. Similar to Schema mode, it uses cardinality to determine arrays and type definitions for values.

Advantage: You do not need to mark repeated elements using XML attributes like in generic mode.

5. Handling Maps​

In JSON, an object can represent a Map (keys to values) where keys are arbitrary strings (e.g., MIME types).

To support this, define a Message Type where elements have cardinality > 1 and at least one non-boolean, non-optional XML attribute. The attribute value is used as the property name of the map.

REST Services​

Context

In the context of REST services, you cannot select a specific message type directly in the serializer. Instead, select the entry "REST Service". The message type configured in the Request/Response of the REST service is used automatically.

QDAS Writer​

Description​

QDAS (also known as AQDEF - Advanced Quality Data Exchange Format) is a file format used to store Quality data from measurement devices. This serializer transforms a structured Message into a QDAS text stream.

Configuration​

  • Encoding: ISO-8859-1, UTF-8, UTF-16BE, or UTF-16LE.
  • Date/Time format: Select the format for Date/Time values (e.g., field K0004).

Message Structure​

The QDAS writer requires a specific message structure. DFD and DFX elements are optional, but at least one of them must exist.